This toolkit provides a comprehensive set of tools for loading, processing, analyzing, and visualizing data from the Solar Orbiter mission, primarily focusing on the STIX, RPW, and EPD instruments. It supports advanced workflows including power-law analysis, event statistics, frequency drift fitting, quicklook plotting, and file/data availability checking. The package is designed for scientific users analyzing solar flare and radio burst data, with both scripting and interactive GUI (Qt-based) workflows.
Key features:
flowchart TD
subgraph DataPreparation["Data Preparation"]
stixRead[stix_read.py]
rpwRead[rpw_read.py]
values[values.py]
fileAvailability[file_availability.py]
end
subgraph Analysis["Analysis and Fitting"]
electronPowerlaw[electron_powerlaw.py]
fitFunctions[fit_functions.py]
freqDrift[freq_drift.py]
flareStatistics[flare_statistics.py]
end
subgraph Visualization["Visualization and Quicklooks"]
quicklooks[quicklooks.py]
end
subgraph GUI["Graphical User Interface"]
sololabApp[sololab_app.py]
end
stixRead --> electronPowerlaw
stixRead --> quicklooks
rpwRead --> freqDrift
rpwRead --> quicklooks
electronPowerlaw --> quicklooks
fitFunctions --> freqDrift
freqDrift --> quicklooks
flareStatistics --> quicklooks
values --> stixRead
values --> rpwRead
values --> fitFunctions
values --> quicklooks
values --> flareStatistics
sololabApp --> quicklooks
sololabApp --> stixRead
sololabApp --> rpwRead
sololabApp --> values
| Module/File | Responsibility |
|---|---|
stix_read.py |
Reading and preprocessing STIX L1/L2 FITS files, background subtraction, file merging |
rpw_read.py |
Reading, filtering, and preprocessing RPW HFR/TNR CDF data, background subtraction, PSD creation, and combination |
values.py |
Constants, date/time formats, utility functions (mean, filtering) used throughout the codebase |
file_availability.py |
File system utilities for data/bkg file discovery, time interval checking, suggestions for background files |
quicklooks.py |
High-level plotting utilities for quicklooks, combined views, overlays, and publication-ready instrument plots |
sololab_app.py |
Qt-based GUI application for data import, interactive parameter selection, and combined plotting |
freq_drift.py |
Fitting time-frequency profiles, extracting exciter velocities and drift rates, and diagnostics for frequency drift phenomena |
flare_statistics.py |
CSV-based flare event table parsing, calculation of delays, heights, and expected parameter estimates |
electron_powerlaw.py |
Electron flux modeling, power-law and double power-law electron distributions, STIX data integration, plotting |
fit_functions.py |
Mathematical model definitions (Gaussian, Weibull, fluorescence, etc.) for scientific fitting and their error metrics |
__init__.py |
Package-wide import aggregator, exposes all public functions/classes for interactive use |
stix_read.py)Handles loading and preprocessing of STIX L1/L2 FITS files, including counts extraction, time/energy bin normalization, background subtraction, time selection, and merging of multiple files.
| Name | Type | Description |
|---|---|---|
stix_create_counts |
function | Reads a STIX FITS file, returns counts per second per energy bin, and time array. |
stix_remove_bkg_counts |
function | Subtracts background using another file or custom time interval, with optional polling function. |
stix_combine_files |
function | Merges multiple count files, optionally with background or energy alignment enforcement. |
stix_combine_counts |
function | Merges multiple in-memory count objects, aligning on time and energy bins. |
Key Behavior:
rpw_read.py)Handles reading and preprocessing of RPW HFR/TNR data from CDF files, PSD computation, background subtraction, and combination of PSDs across files.
| Name | Type | Description |
|---|---|---|
rpw_get_data |
function | Loads RPW L2/L3 CDF files, applies frequency filtering and pre-processing. |
rpw_create_PSD |
function | Creates a Power Spectral Density (PSD) object from loaded data, supports date/frequency selection and background subtraction. |
rpw_create_PSD_L2/L3 |
function | Level-specific PSD creation logic. |
rpw_sort_psd |
function | Ensures PSD arrays are sorted by time/frequency axes. |
rpw_join_psds |
function | Joins multiple compatible PSDs into one (with background aggregation). |
Key Behavior:
values.py)Centralizes all constants for physical units, date/time formats, RPW/STIX index arrays, and common utility functions (e.g., geometric mean, polling functions, filtering NaNs).
filter_nan: Paired filtering of two lists for valid (non-NaN) entries.geo_mean: Computes geometric mean.verbose_dts: Prints time delta statistics from a time array.get_poll_func: Returns polling function by name or percentile.
case-sensitive):
"mean", "geo_mean", "median", "min", "max""P_<value>" where <value> is numeric in [0, 100]
"P_50" (median), "P_95", "P_98.5"file_availability.py)Provides file system tools for scanning directories for STIX/RPW science and background files, checking data availability for date intervals, and providing suggestions for background file selection.
| Name | Type | Description |
|---|---|---|
stix_get_all_bkg_files |
function | Lists all STIX background FITS files in a directory. |
stix_get_all_aux_files |
function | Lists all STIX auxiliary files. |
stix_suggest_bkg_file_for_date |
function | Suggests closest-in-time background files to a given date. |
stix_data_in_interval_exists |
function | Checks if science files cover a given interval. |
rpw_check_date_availability |
function | Checks if RPW CDF files cover a given date. |
check_combined_availability |
function | Reports combined availability for STIX and RPW data. |
save_objects, load_objects |
function | Simple save/load for numpy .npz instrument data packs. |
quicklooks.py)Centralizes all Matplotlib-based visualization routines for quicklooks, overlays, and publication-ready plots for STIX, RPW, and EPD data, including joint and multi-panel displays.
| Name | Type | Description |
|---|---|---|
quicklook_plot |
function | High-level function to generate combined instrument plots with many customization options. |
stix_plot_spectrogram, stix_plot_counts, stix_plot_overlay |
function | STIX-specific plotting routines (spectrogram, integrated counts, overlays). |
stix_plot_bkg |
function | Plots STIX background spectrum (counts/s/keV) versus mean energy from a background-corrected STIX counts object. |
rpw_plot_psd, rpw_plot_curves, rpw_plot_overlay |
function | RPW-specific plotting routines (PSD, integrated curves, overlays). |
rpw_plot_bkg |
function | Plots selected RPW background spectrum versus frequency and overlays per-frequency data maxima. |
rpw_plot_bkg_aggregation |
function | For merged RPW PSDs, plots each component background plus the aggregated background used in the combined PSD. |
paint_markers, ax_paint_grid |
function | Auxiliary functions for plot annotation and formatting. |
plot_ept_data |
function | Plots EPD (particle) time profiles for selected channels. |
Key Behavior:
sololab_app.py)Implements a full-featured Qt (via qtpy) GUI for data import, parameter selection, and interactive plotting. Supports instrument selection, data pack saving/loading, and detailed plotting preferences.
| Class/File | Description |
|---|---|
MainWindow |
Main application window, manages state and orchestrates dialogs. |
ImportStixDialog |
Dialog for loading and previewing STIX data (with background options). |
ImportRpwHfrDialog, ImportRpwTnrDialog |
Dialogs for loading and previewing RPW HFR/TNR data (with background options). |
ImportEpdDialog |
Dialog for downloading and previewing EPD particle data. |
PlotPrefsDialog |
Dialog for setting and saving plotting preferences (energy/frequency bins, log-scaling, overlays, etc.). |
CombinedPlotDialog |
Dialog for selecting displayed instruments and combined figure plotting. |
InstrumentSelectionDialog, EpdChannelSelectionDialog, etc. |
Utility dialogs for instrument/channel/frequency selection. |
sequenceDiagram
participant User
participant GUI as MainWindow
participant Importer as ImportStixDialog/ImportRpwDialog
participant Plotter as quicklook_plot
User->>GUI: Click "Import STIX data"
GUI->>Importer: Show file selection dialog
Importer->>GUI: Returns processed data
GUI->>Plotter: Generate preview/quicklook
Plotter-->>GUI: Returns Matplotlib figure
GUI-->>User: Displays plot in preview area
freq_drift.py)Provides the core algorithms for fitting time-frequency profiles (e.g., type III radio burst drift), extracting drift rates, exciter velocities, and plotting diagnostic results.
| Name | Type | Description |
|---|---|---|
rpw_fit_time_profiles |
function | Fits temporal profiles for all frequency bins using specified model (Gaussian, Weibull, etc.). |
rpw_freq_drifts |
function | Calculates frequency drift rates and uncertainties from fit results. |
rpw_estimate_beam_velocity |
function | Estimates exciter/beam velocities from drift rates with error propagation using density models. |
plot_compare_fits, plot_curve_fits, etc. |
function | Visualization routines for comparing fits, plotting fit overlays, and velocity diagnostics. |
ne_from_freq, freq_from_ne, ne_from_r_leblanc |
function | Electron density model utilities for coronal/heliospheric calculations. |
Key Behavior:
flare_statistics.py)Parses, computes, and augments flare event tables (CSV format) with derived delay times, onset/peak events, and physical expectations based on density models and velocities.
| Name | Type | Description |
|---|---|---|
create_dataframe_from_csv |
function | Loads a flare event table, computes delays between various event times, filters by 'used' flag. |
estimate_expected_heights_delays |
function | Adds columns for expected heights and delays for given velocity values and electron density models. |
electron_powerlaw.py)Provides classes and functions for representing and manipulating electron flux distributions as power-law or double power-law models, including integration with STIX spectroscopy data. Supports extrapolation, integration, and various plotting utilities.
| Name | Type | Description |
|---|---|---|
powerlaw |
class | Models a single power-law electron spectrum with extrapolation, integration, and plotting. |
double_powerlaw |
class | Models a broken/double power-law electron spectrum (two spectral indices, one break energy). |
flux_e_low_from_total_flux |
function | Computes flux at low energy from total flux and spectral index. |
plot_powerlaws |
function | Plots multiple powerlaw/double_powerlaw instances in a combined quicklook. |
process_spectroscopy_table |
function | Processes a STIX spectroscopy result table, extracts key fit parameters, and computes integrated fluxes above energy thresholds. |
Key Behavior:
powerlaw and double_powerlaw provide methods for extrapolation, integration (flux and energy), and Matplotlib visualizations.process_spectroscopy_table parses DataFrame tables from STIX fits, applies powerlaw modeling per row, and adds new columns for integrated flux above thresholds.fit_functions.py)Defines a set of parametric models (Gaussian, Weibull, etc.) and their corresponding error/metric functions for fitting intensity/time profiles in solar data. Centralizes all mathematical models for reuse across analysis routines.
| Name | Type | Description |
|---|---|---|
intensity_model |
class | Encapsulates a fit function, its center, deviation, background, onset, and error calculation methods. |
FUNCTION_CATALOG |
dict | Maps model names to their intensity_model instances for lookup by string. |
get_fit_function |
function | Retrieves a model from the catalog by name. |
get_metric |
function | Returns metric (e.g., RMSE, weighted RMSE) for fit evaluation. |
gaussian, fluorescence, weibull, etc. |
function | Mathematical model functions for use in fitting. |
Key Behavior:
__init__.py)Aggregates all main functions and classes from submodules to provide a flat package namespace for interactive and script imports.
| Class | Location | Responsibility |
|---|---|---|
powerlaw, double_powerlaw |
electron_powerlaw.py |
Electron flux modeling and integration |
intensity_model |
fit_functions.py |
Encapsulates parametric fit functions |
solar_event |
quicklooks.py |
Event annotation for time series plots |
MainWindow |
sololab_app.py |
Main Qt application class |
ImportStixDialog |
sololab_app.py |
STIX data import dialog |
ImportRpwHfrDialog |
sololab_app.py |
RPW HFR data import dialog |
ImportEpdDialog |
sololab_app.py |
EPD data import and download dialog |
try/except blocks to handle file I/O and data format errors, printing relevant messages and failing gracefully.QMessageBox dialogs to inform the user.get_poll_func, get_fit_function, and data loaders print available options if an unknown or invalid argument is supplied.save_objects and load_objects (NumPy .npz).This section adds practical typing/context for the most used functions. Types below use Python-style notation.
%d-%b-%Y %H:%M:%S (example: "11-Nov-2022 09:07:20").[start, end].numpy.ndarray of datetime.datetime or numpy.datetime64.dict)Returned by stix_create_counts and related helpers:
time: array-like[datetime]counts_per_sec: np.ndarray with shape (ntime, nenergy)energy_bins: Astropy table-like object with at least channel, e_low, e_highmean_energy: list[float]background: np.ndarray length nenergydict)Returned by rpw_get_data:
time: array-like[datetime]frequency: np.ndarray (kHz)voltage: np.ndarraytype: "hfr" | "tnr"level: "L2" | "L3"flux.dict)Returned by rpw_create_PSD*:
time: np.ndarray (selected time axis)frequency: np.ndarray (selected frequency axis)v: np.ndarray shape (nfreq, ntime)df: np.ndarray frequency bin spacingt_idx: np.ndarray[int] selected time indicesfreq_idx: np.ndarray[int] selected frequency indicesbkg: np.ndarray | None (background matrix)polling_function: str | Nonetype, level: copied from the source datastix_create_counts(pathfile, is_bkg=False, time_arr=None, date_range=None, correct_flight_time=False, energy_shift=0)pathfile: str path to STIX FITS.is_bkg: bool; when True, computes a background spectrum replicated over time_arr.time_arr: array-like[datetime]; required when is_bkg=True.date_range: list[str] | None; two date strings in standard format.correct_flight_time: bool; applies Earth–spacecraft delay header correction.energy_shift: float|int; additive keV shift for energy bins.stix_remove_bkg_counts(pathfile, pathbkg=None, stix_bkg_range=None, date_range=None, ..., bkg_poll_function='mean')pathfile: str science FITS path.pathbkg: str | None; optional background FITS path.stix_bkg_range: list[str] | None; interval for in-data background estimation.bkg_poll_function: str; accepted formats are:
"mean", "geo_mean", "median", "min", "max""P_<value>" (e.g., "P_95", "P_98", "P_99.5")counts_per_sec background-corrected.stix_combine_files(filenames, bkgfile=None, ..., stix_bkg_range=None, force=False, ...)filenames: list[str] of STIX FITS files.stix_bkg_range: list[list[str] | None] aligned with filenames, or None.force: bool; allows merging even with energy-bin inconsistencies (truncates to common channels).rpw_get_data(file, sensor=None, filter=tnr_remove_idx)file: str path to RPW CDF (HFR/TNR, L2 or L3).sensor: int | None; defaults to 9 for HFR and 4 for TNR.filter: index list/array used for TNR channel filtering.rpw_create_PSD(data, freq_range=None, date_range=None, freq_col=0, proposed_indexes=..., which_freqs='both', rpw_bkg_interval=None, sort=True, bkg_poll_function='mean')data: RPW raw data object from rpw_get_data.freq_range: list[float] | tuple[float,float] | None in kHz.date_range: list[str] | None; [start, end].freq_col: int; column used for HFR frequency extraction in L2.proposed_indexes: array-like[int]; candidate frequency channel indices.which_freqs: str; common values: "both", "non_zero".rpw_bkg_interval: list[str] | None; background interval for subtraction.sort: bool; sorts resulting PSD by time then frequency.bkg_poll_function: str; same format as STIX ("mean", "geo_mean", "median", "min", "max", or percentile "P_<value>").rpw_join_psds(psds, bkg_agg='median', plot_bkg_agg=False)psds: list[dict]; all must have identical level, type, and frequency axis.bkg_agg: str; aggregation method over background spectra.quicklook_plot(...)Most important inputs:
stix_counts: STIX counts object (see schema above).hfr_psd, tnr_psd: RPW PSD object(s).epd_data: pandas.DataFrame indexed by time.epd_energies: channel metadata object from EPD loader (typically dict/DataFrame-like depending on loader return).display: list[str]; combination of "stix", "hfr", "tnr", "epd".date_range: list[str] | None.stix_energy_bins: list[list[float,float]] energy intervals in keV.hfr_frequencies, tnr_frequencies: list[float|int] in kHz.rpw_frequency_range: two-element numeric range in kHz.cmap, figsize, linewidth, fontsize, etc.) follow Matplotlib conventions.{date_string: color_string} format.stix_plot_bkg(l1_counts, ax=None) expects a STIX counts object containing:
mean_energy: energy-bin centers (keV)background: background counts per second per energy bin (added by stix_remove_bkg_counts)rpw_plot_bkg(psd, ax=None) expects an RPW PSD object containing:
frequency, v, bkg, polling_function, type, levelrpw_plot_bkg_aggregation(psd) expects a merged RPW PSD object and additionally requires:
bkg_all: list/array of per-PSD background spectra used during aggregationrpw_fit_time_profiles(rpw_psd, func, time_range, frequency_range, metrics=['rmse'], excluded_freqs=[], tol=0.2, smooth_pts=None, secondary_loop=False, name_tag='')rpw_psd: RPW PSD object.func: intensity_model instance from fit_functions.py (e.g., retrieved by get_fit_function).time_range: list[str] with two date strings.frequency_range: list[float] | tuple[float,float] | None in kHz.metrics: list[str]; examples include "rmse", "wrmse".excluded_freqs: list[float|int] in kHz.tol: float; tolerance for center acceptance bounds.smooth_pts: int | None; moving-average smoothing on log-intensity prior to fit.t, v, f, t0, etc.) plus per-frequency fit entries.freq_drift.py)ne_from_freq(freqs, coef=9.): freqs numeric scalar/array in kHz-equivalent convention used by the codebase.freq_from_ne(ne, coef=9.): ne numeric scalar/array in cm⁻³.r_from_ne(nes, ne_model, ...): ne_model must be a callable f(r)->ne accepting numeric arrays.r_from_freq(freqs, ne_model) and freq_from_r(r, ne_model) use the same density-model callable convention.create_dataframe_from_csv(path, remove_not_used=True)path: str path to CSV table.used filter column.pandas.DataFrame augmented with computed delay columns.estimate_expected_heights_delays(dataframe, density_model=..., name='leblanc', velocities=[...])dataframe: pandas.DataFrame from previous step.density_model: callable f(r)->ne (e.g., ne_from_r_leblanc).name: str suffix/prefix used in generated column names.velocities: list[float] in units of c.flux_e_low_from_total_flux(delta, total, e_low)delta: float spectral index.total: float integrated flux above e_low.e_low: float low-energy threshold (keV).plot_powerlaws(pwlws, e_range, above=False, logx=False, colors=None, styles=None)pwlws: list[powerlaw|double_powerlaw].e_range: two-element numeric range (keV).colors, styles: optional list-like Matplotlib style controls.process_spectroscopy_table(specdata_raw, energy_thresholds=[...], include=['double','single'], time_phase=0)specdata_raw: pandas.DataFrame with STIX spectroscopy-fit columns expected by the routine.energy_thresholds: list[float] in keV.include: list[str]; accepted model families to process.time_phase: int selector for timing phase columns.This package does not expose HTTP REST API endpoints. All data loading, analysis, and plotting are conducted in local Python processes or via the interactive GUI.
This Solar Orbiter Data Analysis Toolkit centralizes all major workflows for multi-instrument solar flare and type III burst analysis, supporting both automated analysis pipelines and interactive exploration via a robust Qt GUI. The codebase is modular, extensible, and uses standard scientific Python libraries for maximum compatibility.
{
"title": "Data Consistency Checks",
"content": "All data merging functions align on energy/frequency bins and check for compatibility, issuing warnings when bins are mismatched."
}
{
"title": "Error Propagation",
"content": "Fit routines compute and propagate parameter uncertainties, supporting robust physical inference from event data."
}
{
"title": "GUI Data Pack Save/Load",
"content": "Users can save all imported and processed data to a pickled pack for reproducibility and quick reloads."
}